/*
 * Copyright 2009 - sanatkumar.padhy
 * 
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *  
 *  	http://www.apache.org/licenses/LICENSE-2.0
 *  
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS, 
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and 
 *  limitations under the License. 
 */
package com.googlecode.simplecrud.dao;

import java.util.List;

/**
 * The generic DAO interface. The only implementation available is
 * {@link SimpleDaoImpl}.
 * 
 * @param <K>
 *            - the key
 * @param <D>
 *            - the entity
 * @see SimpleDaoImpl
 * @author sanatkumar.padhy
 */
public interface SimpleDao<K, D>
{

	/**
	 * This method is used to insert a new record to database.
	 * 
	 * @param dataObject
	 *            - the persistence object to be inserted
	 */
	void insert(D dataObject);

	/**
	 * This method is used to update an existing record on database.
	 * 
	 * @param dataObject
	 *            - the persistence object to be updated
	 */
	void update(D dataObject);

	/**
	 * This method is used to delete records from database using key. If no
	 * attributes of the key are provided every record from the table might be
	 * removed.
	 * 
	 * @param key
	 *            - the key element
	 */
	void delete(K key);

	/**
	 * This method is used to retrieve a record from database using a key. If no
	 * records are found null will be returned. If multiple records are found no
	 * exception will be thrown but the first record will be returned.
	 * 
	 * @param key
	 *            - the key element
	 * @return the persistence object
	 */
	D retrieve(K key);

	/**
	 * This method is used to retrieve a list of records from database using the
	 * key provided. This method does not throw any exception if no records are
	 * found and always returns an empty <code>List</code>.
	 * 
	 * @param key
	 *            - the key element
	 * @return a list of records
	 */
	List<D> retrieveList(K key);

	/**
	 * Check if a record exists based on the key
	 * 
	 * @param key
	 * @return
	 */
	boolean exists(K key);
}
